---
target: Umo Editor Next
keywords: Umo Editor Next,Umo Editor 官网,富文本编辑器,文档编辑器,文档编辑,协同办公
description: Umo Editor 是一个基于 Vue3 和 Tiptap 的本土化开源文档编辑器，专为国人用户设计。它提供了强大的文档编辑能力和 AI 创作功能，支持分页模式、Markdown 语法、富文本编辑、多种格式的节点插入、页面样式设置、文档导出与打印等功能。此外，Umo Editor 还支持自定义扩展、多语言设置和暗色主题。
---

# 文档批注(评论)

文档批注功能允许用户在文档中添加批注，同时支持在多人协作编辑时进行批注。

## 效果截图

![文档批注](https://s2.umodoc.com/demos/comments-cn.png)

## 演示视频

<video src="https://s1.umodoc.com/videos/comments.mp4" controls="true"></video>

## 特点及优势

- 支持私有化部署，您可以通过私有化部署，实现数据的安全性和可控性；
- 支持在线协作，您可以在多人协作编辑时，添加批注；
- 支持离线批注，您可以在离线时，仍然可以添加批注，批注内容会在您重新连接时，自动同步到服务器端；
- 支持各种节点类型和内联添加批注，您可以在文档中添加和管理各类批注；
- 评论中支持 @ 功能，您可以在评论中@其他用户，实现对其他用户的提醒；
- 支持标记已完成/未完成、编辑或删除评论，您可以在批注线程中，对评论进行编辑、删除或标记；
- 支持回复评论，您可以在批注线程中，回复其他评论；
- 支持向评论中添加自定义数据。

## 核心概念

**批注**：文档批注功能中的线程表示一组与某个文档位置关联的评论消息，可以包含多个评论和创建时间，ID 等元数据。线程绑定到文档的某个范围，单条评论包含在线程中。

**评论**：是指批注线程中的单条评论。

**示例**：一个典型的批注线程示例如下：
```js
{
  id: '7ihgradlfp',
  data: {
    user: { id: 'c6x2', name: '用户-c6x2', color: '#7fe67f' },
    ref: '被引用的文字',
  },
  comments: [
    {
      id: 'wls7unwl2t',
      data: { 
        user: { id: 'c6x2', name: '用户-c6x2', color: '#7fe67f' } 
      },
      content: '<p>这是一条批注信息</p>',
      createdAt: '2025-04-14T06:37:12.835Z',
    },
    {
      id: 'v9eabcjenh',
      data: {
        user: { id: 'c6x2', name: '用户-c6x2', color: '#7fe67f' },
        replyId: 'wls7unwl2t',
      },
      content: '<p>这是一条回复信息</p>',
      createdAt: '2025-04-14T06:37:30.035Z',
    },
  ],
  createdAt: '2025-04-14T06:37:12.833Z',
}
```
**接口定义**：线程和评论的接口格式定义如下：

```ts
// 定义线程的接口，包含线程的基本信息和评论列表
interface Thread {
  id: string // 线程唯一标识符
  data: any
  comments: Comment[] // 线程中的评论列表
  createdAt: string // 线程创建时间
  updatedAt?: string // 线程更新时间
  resolvedAt?: string // 线程解决时间
}

// 定义评论的接口，包含评论的基本信息
interface Comment {
  id: string // 评论唯一标识符
  data: any
  content: string // 评论内容
  createdAt: string // 评论创建时间
  updatedAt?: string // 评论更新时间
}
```

## 默认配置

```js
const defaultOptions = {
  // 文档批注相关配置
  comments: {
    enabled: false,
    threads: [], 
    onGetThreads: undefined,
    onSetThread: undefined,
    onCreateThread: undefined,
    onUpdateThread: undefined,
    onDeleteThread: undefined,
    onCreateComment: undefined,
    onUpdateComment: undefined,
    onDeleteComment: undefined,
  },
}
```

## 配置说明

### comments

文档批注相关配置。

- `comments.enabled`：

**说明**：是否开启批注功能

**类型**：Boolean

**默认值**：`true`

- `comments.threads`：

**说明**：批注线程的初始数据。在开启了多人协作编辑时，该选项不生效，线程列表默认从服务商获取。

**类型**：`Array`

**默认值**：`[]`

- `comments.onGetThreads`：

**说明**：获取批注线程列表的回调函数。

**类型**：`Function`

**参数**：`undefined`

**返回值**：`Array`，批注线程列表。

**默认值**：`undefined`

- `comments.onSetThread`：

**说明**：设置批注线程的回调函数。

**类型**：`Function`

**参数**：`thread`，新设置的批注线程。

**默认值**：`undefined`

- `comments.onCreateThread`：

**说明**：创建批注线程的回调函数。

**类型**：`Function`

**参数**：`thread`，新创建的批注线程。

**默认值**：`undefined`

- `comments.onUpdateThread`：

**说明**：更新批注线程的回调函数。

**类型**：`Function`

**参数**：`thread`，更新后的批注线程。

**默认值**：`undefined`

- `comments.onDeleteThread`：

**说明**：删除批注线程的回调函数。

**类型**：`Function`

**参数**：`threadId`，已删除的批注线程 ID。

**默认值**：`undefined`

- `comments.onCreateComment`：

**说明**：创建批注的回调函数。

**类型**：`Function`

**参数**：`comment`，新创建的批注信息。

**默认值**：`undefined`

- `comments.onUpdateComment`：

**说明**：更新批注的回调函数。

**类型**：`Function`

**参数**：`comment`，更新后的批注信息。

**默认值**：`undefined`

- `comments.onDeleteComment`：

**说明**：删除批注的回调函数。

**类型**：`Function`

**参数**：`{threadId, commentId}`，已删除的批注线程 ID 和评论 ID。

**默认值**：`undefined`

## 方法列表

方法的使用示例请参考：[方法列表](../editor/methods)。

### getComments

**说明**：获取批注相关信息。在开启了多人协作编辑功能时，您也可以通过 [`getCollaboration`](./collaboration#getcollaborationinfo)方法，获取到 `provider` 后，通过 `provider` 来获取或设置更多的批注的信息，这要求您对[Hocuspocus](https://tiptap.dev/docs/hocuspocus)有比较深入的了解。

**参数**：无

**返回值**：Object 或 undefined，Object 包含以下信息：
- `connect`：Boolean，是否与服务商连接成功；
- `threads`：Array，当前文档批注线程列表。

## 主题定制

### CSS 变量

您可以通过修改以下 CSS 变量来修改批注的样式。

```css
--umo-thread-background: #ffcc00;
--umo-thread-hover-background: #ffcc0040;
--umo-thread-inline-background: #ffcc00;
--umo-thread-resolved-background: #63c493;
--umo-thread-resolved-hover-background: #63c49340;
```


